NetCloak 3.0 User's Guide: Macros

	Version 3.0 User's Guide

Macros	Previous \| Next Contents

A macro is a block of text or HTML that is defined in a single place which may then be used repeatedly in any of your cloaked documents. This gives you the ability to create a section of HTML text once and then use it repeatedly on many different pages on your server.

For example, many organizations put the same header and footer information on every page of their server. This helps to maintain a consistent look and feel and to make sure that navigational links to the home page, help, or other pages of interest are always available. Using macros, the header and footer can be defined once in a single place and then used on all pages. This makes it easier to create new pages and makes updating the header and footer very quick and simple.

Macros can even contain other macros, or can be used to include entire HTML files inside of an HTML page.

There are two steps in using macros: defining the macros and then using them in your documents. Neither step is complicated.

Defining Macros

Begin by creating a file called "NetCloak.macros" in the "NetCloak Files" folder. This will be a standard text file, so use a text editor of your choice. Even SimpleText will do.

Once the file is open, make sure it is blank and you are ready to create a macro. Use the command <BEGIN_MACRO name> to start each macro, where "name" is the name of your macro. For example, if you want to create a standard header for your documents, you might start your macro with

    <BEGIN_MACRO Header>

Next, enter the HTML text you would like to be inserted when the macro is processed. You may enter as much or as little text as you like. When your macro is complete, end it with the <END_MACRO> command.

An example should make this clear:

    <BEGIN_MACRO NavigationLinks>    <HR>    <A HREF="http://192.1.2.3/Home.html">    Go To Our Home Page</A>    <A HREF="http://192.1.2.3/Help.html">    Get Help</A>    <HR>    <END_MACRO>

Whenever a cloaked document invokes the "NavigationLinks" macro, the text between the BEGIN_MACRO and END_MACRO commands will be inserted.

The NetCloak.macros file may contain as many macros as you like, but the total size of the file must be less than 64k.

Changing Macros

Like NetCloak aliased documents, the macro file is loaded into RAM when NetCloak is started and must be reloaded whenever you make a change. If you add or change a macro, you must have NetCloak reload all the macros. You can quit NetCloak and restart, but additional methods are provided:

Choose "Reload Documents" from the "File" menu within the NetCloak ACGI. (This option is only available if you are using the NetCloak CGI.)
Click the "Reload Documents" button in the "HTML" tab of the "Configuration" window. (This option is also only available in the CGI.)
Click the "Reload Documents" link in the "HTML" page of the Web administration interface.
Send the reload command from a web browser using the URL:
```
    http://your.server.com/NetCloak.acgi$RELOAD 
```
To perform a reload when using the plug-in version, use a URL of "RELOAD" with a "cloaked" suffix, as in:
```
    http://your.server.com/RELOAD.nclk
```

You will note that the Reload command is the same one necessary to reload aliased documents cached in RAM. When you use Reload, both aliased documents and macros will be reloaded.

Using Macros

Any cloaked document can use any macro defined in your NetCloak.macros file. Wherever you want to use a macro, simply use the command <MACRO name>, where "name" is the name of the macro. For example, to use the macro defined above, the cloaked document might end with this HTML text:

    THANK YOU FOR VISITING OUR WEB SITE!
    <MACRO NavigationLinks>    </HTML>

At the bottom of this page, the links to the home page and to the help system would be displayed, just as if they had been put directly into the document.

The MACRO command can also be used to include entire files, in addition to HTML snippets defined in the NetCloak.macros file. In place of the macro name, simply specify a file name, including the path, where appropriate. For example:

    The file "Extra.html" looks like this:
    <P>    <MACRO Extra.html>

In this case, the entire "Extra.html" file will be inserted into the page.

Inserting entire files can be useful when you don't have enough memory to store all of your large macro in the NetCloak.macros file (since the entire file is held in RAM) or when the file being inserted is generated by some other application.

The Macro command will insert files located in the root folder hierarchy. If you would like to insert a file outside the root folder, make a Finder alias to the file and place the alias in the root folder or another folder contained within the root folder. As with aliases in the NetCloak.config file, pathnames must be relative to the root folder and must start with a slash.

Note that if the Security setting 'Prohibit file macros' is enabled, you cannot use the MACRO command to insert the contents of files into your cloaked pages. See the section entitled "Security" for more information.


Copyright © 1996-1999 Maxum Development Corporation http://www.maxum.com/	Previous \| Next Contents